---
title: API
---

## Create Document

<APITable
  request={{
    method: 'POST',
    url: '/universer-api/snapshot/{type}/unit/-/create',
    headers: <code>content-type: application/json</code>,
    parametersType: 'Body',
    parameters: [{
      name: 'type',
      type: 'enum(int)',
      required: true,
      description: '1 (docs), 2 (sheets) path and request body parameters',
    }, {
      name: 'name',
      type: 'string',
      required: true,
      description: 'Document name',
    }, {
      name: 'creator',
      type: 'string',
      required: true,
      description: 'Creator ID',
    }],
    example: `curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\
    -X POST \\
    -H 'Content-Type: application/json' \\
    --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID"}'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'unitID',
      type: 'string',
      description: 'Document ID',
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: 'success',
      },
      unitID: 'ETVf-B4lQqOSE_p09mcp9Q',
    }, null, 2),
  }}
/>

## Get Document List

<APITable
  request={{
    method: 'GET',
    url: '/universer-api/snapshot/{type}/units',
    parametersType: 'Query',
    parameters: [{
      name: 'type',
      type: 'enum(int)',
      required: true,
      description: '1 (doc), 2 (sheet) path and request body parameters',
    }, {
      name: 'nextCursor',
      type: 'string',
      required: false,
      description: 'Next page cursor for pagination',
    }],
    example: `curl -X GET 'http://localhost:8000/universer-api/snapshot/1/units?nextCursor=100'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'units',
      type: 'array[object]',
      description: 'List of documents',
      properties: [{
        name: 'unitID',
        type: 'string',
        description: 'Document ID',
      }, {
        name: 'name',
        type: 'string',
        description: 'Document name',
      }, {
        name: 'type',
        type: 'enum(int)',
        description: '1（doc），2（sheet）',
      }],
    }, {
      name: 'nextCursor',
      type: 'string',
      description: 'Next page cursor for pagination, empty when it is the last page',
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
      units: [{
        unitID: '1',
        name: 'a',
        type: 1,
      }],
      nextCursor: '200',
    }, null, 2),
  }}
/>

## Delete Document

<APITable
  request={{
    method: 'DELETE',
    url: '/universer-api/snapshot/-/units',
    headers: <code>content-type: application/json</code>,
    parametersType: 'Query',
    parameters: [{
      name: 'unitIds',
      type: 'array[string]',
      required: true,
      description: 'Array of document IDs',
    }],
    example: `curl -X DELETE 'http://localhost:8000/universer-api/snapshot/-/units?unitIds=1&unitIds=2'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
    }, null, 2),
  }}
/>

## Upload File

<APITable
  request={{
    method: 'POST',
    url: '/universer-api/stream/file/upload',
    headers: <code>content-type: multipart/form-data</code>,
    parametersType: 'Body',
    parameters: [{
      name: 'size',
      type: 'int',
      required: true,
      description: 'File size (byte), query parameter; the parameter must equal the actual file size, otherwise it will return an error',
    }, {
      name: 'file',
      type: 'Form.file',
      required: true,
      description: 'HTML form file upload',
    }],
    example: `curl 'http://localhost:8000/universer-api/stream/file/upload?size=125466' \\
    --header 'cookie: _univer=XXXXXX' \\
    --form 'file=@"demo.xlsx"'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'FileId',
      type: 'string',
      description: 'File ID, used for subsequent requests such as import and export',
    }],
    example: JSON.stringify({
      FileId: 'xxxx',
    }, null, 2),
  }}
/>

## Import

<APITable
  request={{
    method: 'POST',
    url: '/universer-api/exchange/{type}/import',
    headers: <code>content-type: application/json</code>,
    parametersType: 'Body',
    parameters: [{
      name: 'type',
      type: 'enum(int)',
      required: true,
      description: '1 (doc), 2 (sheet)',
    }, {
      name: 'outputType',
      type: 'enum(int)',
      required: true,
      description: '1 (unit), 2 (json)',
    }, {
      name: 'fileID',
      type: 'string',
      required: true,
      description: 'The ID of the uploaded file',
    }, {
      name: 'minSheetRowCount',
      type: 'int',
      required: true,
      description: 'Minimum row count, the import will check if the sheet row count meets the requirement',
    }, {
      name: 'minSheetColumnCount',
      type: 'int',
      required: true,
      description: 'Minimum column count, the import will check if the sheet column count meets the requirement',
    }],
    example: `curl -X POST 'http://localhost:8000/universer-api/exchange/2/import' \\
    -H 'Content-Type: application/json' \\
    --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20}'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'taskID',
      type: 'string',
      description: 'Conversion task ID, import and export are asynchronous, use this ID to poll the interface for conversion results',
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
      taskID: '456',
    }, null, 2),
  }}
/>

## Export

<APITable
  request={{
    method: 'POST',
    url: '/universer-api/exchange/{type}/export',
    headers: <code>content-type: application/json</code>,
    parametersType: 'Body',
    parameters: [{
      name: 'type',
      type: 'enum(int)',
      required: true,
      description: '1 (doc), 2 (sheet)',
    }, {
      name: 'unitID',
      type: 'string',
      required: true,
      description: 'Document ID',
    }, {
      name: 'sscSwitch',
      type: 'boolean',
      required: false,
      description: 'Whether to enable SSC (Server Side Calculation), set to true to trigger server-side formula calculation, default is false',
    }],
    example: `curl -X POST 'http://localhost:8000/universer-api/exchange/2/export' \\
    -H 'Content-Type: application/json' \\
    --data-raw '{"unitID":"xxxx","type":2}'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'taskID',
      type: 'string',
      description: 'Conversion task ID, import and export are asynchronous, use this ID to poll the interface for conversion results',
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
      taskID: '456',
    }, null, 2),
  }}
/>

## Get Conversion Result

<APITable
  request={{
    method: 'GET',
    url: '/universer-api/exchange/task/{taskID}',
    parametersType: 'Path',
    parameters: [{
      name: 'taskID',
      type: 'string',
      required: true,
      description: 'Conversion task ID',
    }],
    example: `curl -X GET 'http://localhost:8000/universer-api/exchange/task/123'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'status',
      type: 'enum(string)',
      description: '"pending", "done", "failed"',
    }, {
      name: 'export',
      type: 'object',
      properties: [{
        name: 'fileID',
        type: 'string',
        description: 'The file ID of the export conversion result, used for subsequent requests to get file content',
      }],
    }, {
      name: 'import',
      type: 'object',
      properties: [{
        name: 'unitID',
        type: 'string',
        description: 'The unit ID after import conversion, used to open the online spreadsheet',
      }, {
        name: 'jsonID',
        type: 'string',
        description: 'The file ID of the import conversion result in JSON format, used for subsequent requests to get file content',
      }],
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
      status: 'done',
      export: {
        fileID: '456',
      },
      import: {
        unitID: '789',
        jsonID: '012',
      },
    }, null, 2),
  }}
/>

## Get File

<APITable
  request={{
    method: 'GET',
    url: '/universer-api/file/{fileID}/sign-url',
    parametersType: 'Path',
    parameters: [{
      name: 'fileID',
      type: 'string',
      required: true,
      description: 'The file ID of the conversion task result',
    }],
    example: `curl -X GET 'http://localhost:8000/universer-api/file/1234/sign-url'`,
  }}
  response={{
    type: 'application/json',
    parameters: [{
      name: 'error',
      type: 'object',
      properties: [{
        name: 'code',
        type: 'enum(int)',
        description: '1 (success)',
      }, {
        name: 'message',
        type: 'string',
        description: 'The information of fail situation',
      }],
    }, {
      name: 'url',
      type: 'string',
      description: 'The download URL of the file',
    }],
    example: JSON.stringify({
      error: {
        code: 1,
        message: '',
      },
      url: 'https://example.com/path/to/file.xlsx',
    }, null, 2),
  }}
/>
